<!-------- @HEADER
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 !  Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
 !                  Copyright 2012 Sandia Corporation
 !
 ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
 ! the U.S. Government retains certain rights in this software.
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are
 ! met:
 !
 ! 1. Redistributions of source code must retain the above copyright
 ! notice, this list of conditions and the following disclaimer.
 !
 ! 2. Redistributions in binary form must reproduce the above copyright
 ! notice, this list of conditions and the following disclaimer in the
 ! documentation and/or other materials provided with the distribution.
 !
 ! 3. Neither the name of the Corporation nor the names of the
 ! contributors may be used to endorse or promote products derived from
 ! this software without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
 ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
 ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 !
 ! Questions? Contact Karen Devine	kddevin@sandia.gov
 !                    Erik Boman	egboman@sandia.gov
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 ! @HEADER
-------> 
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
   <meta name="sandia.approved" content="SAND99-1376">
   <meta name="author" content="karen devine, kddevin@sandia.gov">
   <title> Zoltan Developer's Guide:  Data Types</title>

</head>
<body bgcolor="#FFFFFF">

<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_lb_structs.html">Next</a>&nbsp; |&nbsp; <a href="dev_lb_interface.html">Previous</a></i></b></div>

<h2>
<a NAME="interface_types"></a>ID Data Types</h2>
Within Zoltan, objects are identified by a global
identification (ID) value provided by the application. This global ID must
be unique across all processors. The application may also provide a local
ID value that it can use for faster location of objects within its own
data structure. For example, local array indices to objects' data may be
provided as the local IDs; these indices can then be used to directly access
data in the query functions. Zoltan does not use these
local IDs, but since it must pass them to the application in the interface
query functions, it must store them with the objects' data.&nbsp; ID data
types and macros for manipulating IDs are described below.
<blockquote><a href="#ID arrays">IDs and Arrays of IDs</a>
<br><a href="#ID alloc">Allocating IDs</a>
<br><a href="#ID Ops">Common Operations on IDs</a></blockquote>

<h4>
<a NAME="ID arrays"></a>IDs and Arrays of IDs</h4>
Zoltan stores each global and local ID as an array of unsigned integers.
Arrays of IDs are passed to the application as a one-dimensional array
of unsigned integers with size
<i>number_of_IDs</i> * <i>number_of_entries_per_ID</i>.
A type definition <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
(in <i>include/zoltan_types.h</i>) points to an ID or array of IDs. The number
of array entries per ID can be set by the application using the <a href="../ug_html/ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and
<a href="../ug_html/ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>
parameters.
<h4>
<a NAME="ID alloc"></a>Allocating IDs</h4>
Macros that simplify the allocation of global and local IDs are described
in the table below. These macros provide consistent, easy-to-use memory
allocation with error checking and, thus, their use is highly recommended.&nbsp;
Each macro returns NULL if either a memory error occurs or the number of
IDs requested is zero.
<br>&nbsp;
<table BORDER WIDTH="100%" NOSAVE >
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_MALLOC_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>);</td>

<td>Allocates and returns a pointer to a single global ID.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_MALLOC_LID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>);</td>

<td>Allocates and returns a pointer to a single local ID.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_MALLOC_GID_ARRAY</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, int <i>n</i>);</td>

<td>Allocates and returns a pointer to an array of <i>n</i> global IDs,
where the index into the array for the <i>i<sup>th</sup></i> global ID
is <i>i</i>*<a href="../ug_html/ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_MALLOC_LID_ARRAY</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, int <i>n</i>);</td>

<td>Allocates and returns a pointer to an array of <i>n</i> local IDs,
where the index into the array for the <i>i<sup>th</sup></i> local ID is
<i>i</i>*<a href="../ug_html/ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_REALLOC_GID_ARRAY</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz,</i> <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>ptr</i>, int <i>n</i>);</td>

<td>Reallocates and returns a pointer to an array of<i> n</i> global IDs,
replacing the current array pointed to by<i> ptr</i>.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_REALLOC_LID_ARRAY</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz,</i> <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>ptr</i>, int <i>n</i>);</td>

<td>Reallocates and returns a pointer to an array of<i> n</i> local IDs,
replacing the current array pointed to by<i> ptr</i>.</td>
</tr>
</table>

<h4>
<a NAME="ID Ops"></a>Common Operations on IDs</h4>
In addition, macros are defined for common operations on global and local
IDs.&nbsp; These macros include error checking when appropriate and account
for different values of <a href="../ug_html/ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and <a href="../ug_html/ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>.&nbsp;
Use of these macros improves code robustness and simplifies code maintenance;
their use is highly recommended.
<br>&nbsp;
<table BORDER WIDTH="100%" NOSAVE >
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>void<b> ZOLTAN_INIT_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>id</i>);</td>

<td>Initializes all entries of the global ID <i>id</i> to zero; <i>id</i>&nbsp;
must be allocated before calling <b>ZOLTAN_INIT_GID</b>.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE>void<b> ZOLTAN_INIT_LID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>id</i>);</td>

<td>Initializes all entries of the local ID <i>id</i> to zero; <i>id</i>&nbsp;
must be allocated before calling <b>ZOLTAN_INIT_LID</b>.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE>void<b> ZOLTAN_SET_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>tgt</i>,
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>src</i>);</td>

<td>Copies the global ID <i>src</i> into the global ID <i>tgt</i>.&nbsp;
Both <i>src</i> and <i>tgt</i> must be allocated before calling <b>ZOLTAN_SET_LID</b>.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE>void<b> ZOLTAN_SET_LID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>tgt</i>,
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>src</i>);</td>

<td>Copies the local ID <i>src</i> into the local ID <i>tgt</i>.&nbsp;
Both <i>src</i> and <i>tgt</i> must be allocated before calling <b>ZOLTAN_SET_LID</b>.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE>int<b> ZOLTAN_EQ_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>a</i>,
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>b</i>);</td>

<td>Returns TRUE if global ID<i> a</i> is equal to global ID <i>b</i>.</td>
</tr>
<!-------------------- KDD COMMENTED OUT WHILE NOT USED IN CODE
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>int<b> ZOLTAN_LT_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>a</i>,
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>b</i>);</td>

<td>Returns TRUE if global ID<i> a</i> is less than global ID <i>b.</i></td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE>int<b> ZOLTAN_GT_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>a</i>,
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>b</i>);</td>

<td>Returns TRUE if global ID<i> a</i> is greater than global ID <i>b.</i></td>
</tr>
-------------------->

<tr VALIGN=TOP NOSAVE>
<td NOSAVE>void<b> ZOLTAN_PRINT_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>id</i>);</td>

<td>Prints all entries of a single global ID <i>id</i>.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td>void<b> ZOLTAN_PRINT_LID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>id</i>);</td>

<td NOSAVE>Prints all entries of a single local ID <i>id</i>.</td>
</tr>
</table>

<p>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_lb_structs.html">Next:&nbsp;
Data Structures</a>&nbsp; |&nbsp; <a href="dev_lb_interface.html">Previous:&nbsp;
Interface Functions</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>
